.TH FTP 1
.SH NAME
ftp \- Internet file transfer program
.SH SYNOPSIS
.B ftp
.RB [ \-v ] 
.RB [ \-d ]
.RB [ \-i ]
.RB [ \-A ]
.RB [ \-P ]
[
.B \-p 
.I password
] [
.B \-u 
.I username
]
.RB [ \-q ]
.RI [ host
[
.I port
] ]
.SH DESCRIPTION
.B Ftp
is the user interface to the Internet standard File Transfer Protocol.
The program allows a user to transfer files to and from a
remote network site.
.PP
The client host with which 
.B ftp
is to communicate may be specified on the command line.
If this is done,
.B ftp
will immediately attempt to establish a connection to an FTP
server on that host - unless the 
.B \-n
('auto-connect') option is present. Further, if the
.B \-u
and
.B \-p
options (username and password) are present,
. ftp
will attempt  a complete login to the remote host before entering 
its command interpreter and await instructions from the user. When 
.B ftp
is awaiting commands, the prompt `ftp>'
is provided to the user.  The following commands are recognized
by
.BR ftp .
Commands may be abbreviated to 3 characters.
.TP
\fB\&!\fP [ \fIcommand\fP [ \fIargs\fP ] ]
Execute local commands via the shell.
The first token is taken to be a command to execute
directly, with the rest of the arguments as its arguments.
Without arguments, the command is ignored.
.TP
.B ascii
Set file transfer mode to ASCII, which means that the content is assumed to be text and
<CR><LF> line endings are assumed.
.TP
.B binary
Set the file transfer
.I type
to support binary image transfer.
.TP
.B bye
Terminate the FTP session with the remote server
and exit
.BR ftp .
An end of file (^D) will also terminate the session and exit.
.TP
.BI cd " remote-directory"
Change the working directory on the remote machine
to 
.IR remote-directory .
.TP
.B close
Terminate the currently open session and
return to the command interpreter.
.TP
.BI delete " remote-file"
Delete the file
.I remote-file
on the remote machine.
.TP
\fBdebug\fP [ \fIdebug-value\fP ]
Set or report the debug level which determines the amount of detail in messages during operation.  If an optional
.I debug-value
is specified, it is used to set the debug level. Values above 4 are not meaningful.
Note that the 
.I verbose
command will set the debug-value to either 0 or one (toggle).
When debugging is on,
.B ftp
prints each command sent to the remote machine, preceded
by the string `--->'. A number of other messages and numbers will also be printed, depending on the level.
If 
.I debug
is off, only minimal information is displayed, such as the file names transferred.
.TP
\fBdir\fP [ \fIremote-directory\fP ] [ \fIlocal-file\fP ]
Print the contents of the
current (remote) directory, or - if
.I remote-directory
is specified - list that directory.
Optionally, if 
.I local-file 
is specified, place the output in that file.
If no local file is specified, or \fIlocal-file\fP is \fB-\fP,
output comes to the terminal.
.TP
\fBget\fP \fIremote-file\fP [ \fIlocal-file\fP ]
Fetch 
.I remote-file
from the FTP server. If
.I local-file
is left unspecified, the remote file name is used. Note that the remote server may
be case sensitive, which means that 'SETUP.DAT', 'setup.dat' and 'Setup.DAT' are different
files.
.TP
\fBglob\fP
Toggle filename expansion for \fBmget\fP and \fBmput\fP.
If globbing is turned off with \fBglob\fP, the file name arguments
are taken literally and not expanded.
Globbing for \fBmput\fP is done as in 
.BR sash (1).
For \fBmget\fP, each remote file name is expanded
separately on the remote machine and the lists are not merged.
Expansion of a directory name is likely to be 
different from expansion of the name of an ordinary file:
the exact result depends on the foreign operating system and ftp server,
and can be previewed by doing `\fBmls\fP\ \fIremote-files\fP\ \fB-\fP' (not currently implemented).
Note:  \fBmget\fP and \fBmput\fP are not meant to transfer
entire directory subtrees of files.  That can be done by
transferring a
.BR tar (1)
archive of the subtree in binary mode.
When transferring full directories, using `*' may some times
(large directories, long filenames) cause
.B ftp
to run out of memory. In such cases, try `.' instead.
.TP
.B hash
Toggle hash-sign (``#'') printing for each data block
transferred.  The size of a data block is 1024 bytes
(currently not implemented).
.TP
\fBhelp\fP
Prints a list of the known commands with a short explanation.
.TP
\fBlcd\fP [ \fIdirectory\fR ]
Change the working directory on the local machine.  If
no 
.I directory
is specified, the current local directory is listed.
.TP
\fBmget\fP \fIremote-files\fP
Expand the \fIremote-files\fP on the remote machine
and do a \fBget\fP for each file name thus produced.
See \fBglob\fR for details on the filename expansion.
.B ftp 
is not doing any filename translation, so file names will be coerced into the
format accepted by the destination file system (minix or FAT).
.TP
\fBmkdir\fP \fIdirectory-name\fP
Make a directory on the remote machine.
.TP
.TP
\fBmput\fP \fIlocal-files\fP
Expand wild cards in the list of local files given as arguments
and do a \fBput\fR for each file in the resulting list.
See \fBglob\fP for details of filename expansion.
.TP
\fBopen\fP \fIhost\fP [ \fIport\fP ]
Establish a connection to the specified
.I host
FTP server.  An optional port number may be supplied,
in which case, 
.B ftp
will attempt to contact an FTP server at that port.
If the 
.I auto-connect
option is on (default), 
.B ftp
will also attempt to automatically connect - and potentially log the user in - to
the FTP server (see below).
.TP
.B prompt
Toggle interactive prompting.  Interactive prompting
occurs during multiple file transfers to allow the
user to selectively retrieve or store files.
If prompting is turned off (default is on), any \fBmget\fP or \fBmput\fP
will transfer all files.
The options are y/n/q where `q' will cause exit to the 
.B ftp
command prompt. This is particularly useful because a ^C
will terminate the 
.B ftp
program, not the current transfer.
.TP
\fBput\fP \fIlocal-file\fP [ \fIremote-file\fP ]
Store a local file on the remote machine.  If 
.I remote-file
is left unspecified, the local file name is used.
.TP
.B pwd
Print the name of the current working directory on the remote
machine.
.TP
.B quit
A synonym for
.BR bye .
.TP
\fBrename\fP [ \fIfrom\fP ] [ \fIto\fP ]
Rename the file
.I from
on the remote machine, to the file
.IR to .
.TP
.B reset
Clear reply queue.
This command re-synchronizes command/reply sequencing with the remote
ftp server.
Resynchronization may be necessary following a violation of the ftp protocol
by the remote server. This command is currently not implemented.
.TP
.BI rmdir " directory-name"
Delete a directory on the remote machine.
.TP
.BI passive
toggles the file transfer mode between `passive' and `port' modes. Port mode is the traditional
method in which the client sends and IP-address and a port number for the server to connect to.
.B ftp
creates a new connection for each file transfer and each directory transfer. Since `Port' mode for obious reasons
doesn't work with NAT (Netwok Address Translation), `Passive' mode was introduced. In passive mode, the roles are reversed,
and the server tells the client which IP-address and port number to use for each file transfer. Passive mode is the default.
Because of the nature of TCP connection establishment, there may be speed differences between the modes 
when transferring many files (`mget', `mput').
.TP
.B status
Show the current status of local parameters and the connection if any.
.TP
.B system
Show the type of operating system running on the remote machine.
.TP
\fBtype\fP [ \fItype-name\fP ]
Set the file transfer
.I type
to
.IR type-name .
If no type is specified, the current type
is printed.  The default type is network ASCII.
When opening a connection,
.B ftp
requests `status' from the remote system in order to determine a reasonable default `type'. 
I.e. if the remote system us Unix/linux, the default `type' is set to binary.
.TP
.B verbose
Toggle verbose mode.  Verbose mode is equivalent to debug level 1.
.TP
\fB?\fP
A synonym for help.
.PP
Command arguments which have embedded spaces may be quoted with
quote (") marks.
.SH "ABORTING A FILE TRANSFER"
[This functionality is currently not implemented in the ftp client.]
To abort a file transfer, use the terminal interrupt key
(usually Ctrl-C).
Sending transfers will be immediately halted.
Receiving transfers will be halted by sending a ftp protocol ABOR
command to the remote server, and discarding any further data received.
The speed at which this is accomplished depends upon the remote
server's support for ABOR processing.
If the remote server does not support the ABOR command, an `ftp>'
prompt will not appear until the remote server has completed
sending the requested file.
.PP
The terminal interrupt key sequence will be ignored when
.B ftp
has completed any local processing and is awaiting a reply
from the remote server.
A long delay in this mode may result from the ABOR processing described
above, or from unexpected behavior by the remote server, including
violations of the ftp protocol.
If the delay results from unexpected remote server behavior, the local
.B ftp
program must be killed by hand.
.SH OPTIONS
Options may be specified at the command line, or to the 
command interpreter.
.PP
The 
.B \-A
(active) option makes \fIport\fR mode the default when entering the 
.B ftp
command prompt (see also the 
.B passive
command above.
.PP
The 
.B \-P
(passive) option does the opposite, this is the default mode.
.PP
The
.B \-v
(verbose on) option is equivalent to setting `-d' or `-d 1'.
.PP
The
.B \-n
option restrains 
.B ftp
from attempting \*(lqauto-connect\*(rq upon initial connection.
If auto-connect is enabled and the 
.B \-u 
and 
.B \-p
options (see below) are not used, 
.B ftp
will prompt for the remote machine login name (default is 'ftp')
and, if necessary, prompt for a password
and an account with which to login.
.PP
The
.B \-i
option turns off interactive prompting during
multiple file transfers.
.PP
The
.B \-d
option enables debugging, and may be followed by a positive number indication the level of verbosity.
Numbers above 4 are not meaningful.
.PP
The
.B \-g
option disables file name globbing.
.PP
.B \-u \fIusername\fR
Use this username as the default when loggin on to the remote server. If the
.B \-p
option is present, 
.B ftp
will attempt to autologin at startup.
.PP
.B \-p \fIpassword\fR
Use this password to attempt auto-login to the remote server. If auto-login fails, the connection will be closed and the 'ftp>' prompt will appear. A new connection may be established using the
'open' command.
.SH "QEMU support"
When running ftp inside the QEMU emulator, use the 
.B \-q option with 
.B ftp 
in order to map addresses and ports correctly. With this option, `passive' mode file transfers
between the local system and the host are fully supported. If connecting inside the system (loopback), both `passive' 
and `port' modes work.
.SH "SEE ALSO"
ftpd(8)
ftpput(1)
ftpget(1)
.PP
For more details refer to the 
.I TLVC file transfer wiki.
.SH BUGS
Correct execution of many commands depends upon proper behavior
by the remote server.
.PP
File name mapping beween hosts with different OSes are undefined and may yield unpredictable results. Use tar-files for better predictability.
.PP
File modes are neither queried not preserved. 
.PP
When using globbing to fetch a remote directory and that directory contains a directory, behaviour is unspecified and server OS dependent.
.PP
The 
.B ftp
client has no support for command line history or editing.
